R/sink rate.R

In mlrioux/sinkworx: Import, Model, and Plot Cell Sinking Data

# June 7, 2019

#'@title Calculate cell sinking rates from segmented regression parameters
#'@description Uses segmented regression parameters to estimate cell sinking rates. For a given well, a sinking rate in millimeters per minute is computed for each segment of the regression model (i.e., 3 rates per well). It is then up to the user to select which of the three sinking rates best represents the data. Sinking rates are calculated as follows: sinking rate = slope/(y-intercept - well bottom) * sample depth
#'@usage sink_rate(database_fits, sample_depth = 3.8, export_output = FALSE, save_as = "Sinking_Rates.csv")
#'@param database_fits dataframe containing the segmented regression parameters that will be used to calculate sinking rate. Generated by running sink_fit().
#'@param sample_depth height of sample in the well,in mm. Depends on the sample volume and plate size; for 300 uL samples in 96-well plates, the sample depth is 3.8 mm.
#'@param fit_param whether all parameters generated by the segmented regression fits (i.e. slopes, breakpoints, intercepts) should remain in the final dataframe. If FALSE, a trimmed version including the well data, sinking rates, and confidence intervals will be generated instead.
#'@param export_output whether the resulting dataframe should be exported to .csv.
#'@param save_as desired filename, if results are to be exported.
#'@return A dataframe containing sinking rate estimates, with each row representing a single well. A rate will be calculated for each segment of the regression (i.e., each slope will have a corresponding sinking rate). 95% upper and lower confidence intervals on each rate are also computed.
#'@examples
#'rates <- sink_rate(database_fits, sample_depth = 5, export_output = T, save_as = "Sink_Rates")
#'@note Rates cannot be estimated without obtaining the segmented regression parameters first. There is currently no screening process in place to select the most representative sinking rate across wells/replicates, so it remains up to the user to select the rates they wish to compare across samples. It is also worth noting that sinking rates of samples with different sample depths must be estimated separately.
# ----------------------------------------------------------------------------

sink_rate <- function(database_fits, sample_depth = 3.8, fit_param = TRUE, export_output = FALSE, save_as = "Sinking_Rates.csv") {

# ----------------------------------------------------------------------------

  plot_by <- paste(database_fits$Plate, database_fits$Well)

  wells <- unique(plot_by)

  Sink_Rates <- NULL

  for (w in 1:length(wells)) {

    focus_well <- wells[w]

    well_data <- dplyr::filter(database_fits, focus_well == plot_by)

    # Calculate 3 sinking rates

    sink_rate_1 <- - ((well_data$slope_1) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_1_LCI <- - ((well_data$slope_1_LCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_1_UCI <- - ((well_data$slope_1_UCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_rate_2 <- - ((well_data$slope_2) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_2_LCI <- - ((well_data$slope_2_LCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_2_UCI <- - ((well_data$slope_2_UCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_rate_3 <- - ((well_data$slope_3) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_3_LCI <- - ((well_data$slope_3_LCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth

    sink_3_UCI <- - ((well_data$slope_3_UCI) / (well_data$intercept_1 - well_data$well_bottom)) * sample_depth


    if (fit_param == TRUE) {

      sink_rates <- as.data.frame(cbind(well_data[1, ],
                                     sink_rate_1, sink_rate_2, sink_rate_3,
                                     sink_1_LCI, sink_1_UCI,
                                     sink_2_LCI, sink_2_UCI,
                                     sink_3_LCI, sink_3_UCI))

    } else if (fit_param == FALSE) {

      # MAKE DATAFRAME WITHOUT SLOPE PARAMETERS

    }



    Sink_Rates <- rbind(Sink_Rates, sink_rates)

  } # end of loop through wells

  if (export_output == TRUE) {

    write.csv(Sink_Rates, file = save_as, row.names = F)

  } # close export

  return(Sink_Rates)

} # end of function